<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<link rel="stylesheet" href="../style/journal.css" type="text/css" />
<style type="text/css"><!--
.googleadsense {
	margin: 2px;
	padding: 0px;
//--></style><script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-65008-1";
urchinTracker();
</script><title>怎么写POD</title>
</head>
<body>
<a href="index.html">Journal</a>(2005) | <a href="../blog/"><b>Blog</b></a>(2006) | <a href="http://www.fayland.org/cgi-bin/random_link.pl">RandomLink</a> | <a href="AboutFayland.html">WhoAmI</a> | <a href="LiveBookmark.html">LiveBookmark</a> | <a href="http://www.fayland.org/">HomePage</a>
<p><&lt;Previous: <a href="RSS.html">给网页增加RSS</a>&nbsp;&nbsp;>>Next: <a href="050115.html">gb2312.enc</a></p>
<h1>怎么写POD</h1>
<div class='content'>
<p>Category: <a href='Basic.html'>Basic</a> &nbsp; Keywords: <b>pod</b></p><h2>简介</h2>
pod(Plain Old Documentation), 它是一种简单而易用的标记型语言（置标语言），用于perl程序和模块中的文档书写。<br />
pod中用段分可以分为三种，普通段落，字面段落（Verbatim Paragraph）和命令段落。<br />
三者的区分非常简单，以=pod|head1|cut|over等指示字开始的段落为命令段落，以空格或制表符（\t）等缩进开始的段落为字面段落，其余的就是普通段落。<br />
pod中有其独特的<a href='#format_code'>格式代码</a>来表现粗体，斜体，超链接等。<br />
<b>对于字面段落是不进行格式代码转义的</b>。pod2html时用<code>&lt;pre></code>将其包围。所以字面段落适合引用语言与代码块。<br />
值得注意的是，对于pod2xxx脚本来说，<b>段落意味着前有一个空行后也有一个空行</b>。<br />
下面着重介绍的pod都是为了pod2html而准备。<br />

<h2>命令指示字</h2>
=head1<br />
=head2<br />
=head3<br />
=head4<br />
此四个指示字生产指定级别的标题。pod2html时用其对应的<code>&lt;h1> .. &lt;/h4></code>包围此段落，并且自动生成a的命名/name和索引/index.<p />
一个简单的例子：<br />
<pre>
=head1 NAME

pod2html - convert .pod files to .html files

</pre>
pod2html后NAME的标签为h1, 而后面的那段为p。<p />

=pod<br />
=cut<br />
=pod 只告诉编译器pod文档开始了，而=cut则是pod文档的结束。<p />
一个简单的例子：<br />
<pre>return;
}

=pod

Here we start our pod

=cut

sub _ {
</pre><p />

=over NUMBER<br />
=item SYMBOL<br />
=back<br />
这三者是连上一起的。=over后面必须要跟一个=back，而这两者之间最少要有一个=item，同时不能有=head1..4。<br />
pod2html时依据item后面的SYMBOL不同将其转化为<code>&lt;dl>&lt;ol>&lt;ul></code>中的一种。<br />
当SYMBOL为数字时使用ol, SYBMOL为*时使用ul, 其余的使用dl.<br />
而=over后面的NUMBER只是确定缩进的空格。不同的格式器(pod2xxxx)将其不同地处理，有些格式器对此进行忽略。默认的NUMBER为4.<br />
=item 能自动生成a的命名，但不参加索引/index（与head不同）。<p />
一个简单的例子：<br />
<pre><code>
=over 4

=item L&lt;http://www.perl.com/>

Perl 的首页 (由欧莱礼公司维护)

=item L&lt;http://www.cpan.org/>

Perl 综合典藏网 (Comprehensive Perl Archive Network)

=item L&lt;http://lists.perl.org/>

Perl 邮递论坛一览

=back

</code></pre>
此例子摘自perlcn.pod<p />

=for format text<br />
=begin format<br />
=end format<br />
此指示字的作用是对此段落使用特殊的格式/format（如html, text等）。<br />
=for与=begin+=end作用相同。区别在于=for只处理一个段落，而=begin+=end能处理它们中间的多个段落。<br />
format为html时，可以用于增加“命令指示字和<a href='#format_code'>格式代码</a>”都不能实现的特殊格式。如<code>&lt;img</code>或其它html标签。<p />
一个简单的例子：<br />
<pre><code>
=begin html

&lt;hr> &lt;img src="thang.png">
&lt;p> This is a raw HTML paragraph &lt;/p>

=end html
</code></pre>
pod2html时会原文拷贝此段代码。<p />

=encoding<br />
用于制定文档的编码，默认为不指定。<p />

<h2><a name='format_code'>格式代码</a></h2>
格式代码可以用于除字面段落外的所有段落，包括命令段落。<br />
<ul>
<li>I<code>&lt;text></code><br />
用斜体表示text, 效果如<i>text</i></li>
<li>B<code>&lt;text></code><br />
用粗体表示text, 效果如<b>text</b></li>
<li>C<code>&lt;code</code>><br />
pod2html时用<code>&lt;code</code>>包围。</li>
<li>L<code>&lt;text|name/sec></code><br />
超链接。<br />
其中name可以为模块名，也可以为一个网址。pod2html时，当name为模块名时转化为module/name.html.name为a里href参数内容<br />
其中text为连接所显示的内容，若没有text，name为模块名时显示 the module::name manpage, <b>name为网址时不允许存在text</b>。pod2html时转化为<code>&lt;a>和&lt;/a></code>之间的东西。<br />
sec参数当name为模块名时指向该模块名的sec部分，没有name时指向当前页的sec部分。此sec部分一般为=head或=item所定义。pod2html时转化为href里的#部分。<br />
<pre>正确的：
L<code>&lt;Net::Ping></code> - <code>&lt;a href="/Net/Ping.html">the Net::Ping manpage&lt;/a></code>
L<code>&lt;http://www.1313s.com></code> - <code>&lt;a href='http://www.1313s.com'>http://www.1313s.com/&lt;/a></code>
L<code>&lt;Perl Error Messages|perldiag> - &lt;a href='perldiag.html'>Perl Error Message&lt;/a></code>
L<code>&lt;perlsyn/"For Loops"> - &lt;a href='perlsyn.html#for_loops'>the perlsyn manpage&lt;/a></code>

错误的：
L<code>&lt;fayland|http://www.1313s.com> - name为网址时不允许存在text
</code></pre></li>
<li>E<code>&lt;escape></code><br />
字符转义。
<ul>
<li>E<code>&lt;lt></code> - <</li>
<li>E<code>&lt;gt></code> - ></li>
<li>E<code>&lt;verbar></code> - |</li>
<li>E<code>&lt;sol></code> - /</li>
<li>更多的请参考perldoc <a href='http://search.cpan.org/perldoc?perlpod'>perlpod</a></li>
</ul>
<li>更多的如<code>F&lt;filename>, S&lt;text></code>等请参考perldoc <a href='http://search.cpan.org/perldoc?perlpod'>perlpod</a></li><br />
</ul>

<h2>Examples</h2>
一个简单的例子用以加深印象。<br />
<pre><code>
=pod

=head1 Examples

it's just a examples for pod newcomer.

=head1 how to write a pod?

=over 4

=item 1

know all pod command's meanings such as "head1, over, item, begin".

=item 2

try to write a example by yourself.

=item 3

use 'pod2html' utility convert pod to html format.

=item 4

modify and pod2html again until u a satisfied.

=back

=head1 FAQ

=head2 want to add a B&lt;img>?

use code as follows:

 =begin html
 
 &lt;img src='http://www.1313s.com/f/fayland_gmail.png' />
 
 =end html

=head2 how to add E&lt;lt>bE&lt;gt> etc.

 E&lt;lt>bE&lt;gt>

=head1 link I&lt;this> page

L&lt;http://www.1313s.com/f/POD.html>

=cut
</code></pre>

<h2>perldoc & pod2html</h2>
pod可以转化为n多种格式。在bin目录下以pod2开头的工具有很多，也有2pod的工具。但最常用的是perldoc和pod2html.<br />
perldoc用于在命令控制台下查看pod文档，而pod2html则把pod转化为html格式。<br />
<h3>pod2html</h3>
你可以通过pod2html --help来查看pod2html的所有参数。因为所有的参数都是很容易看懂的，也就不多加解释了。<br />
将上面的例子保存为examples.pod, 然后进入控制台/console：
<pre><code>pod2html &lt;examples.pod >examples.html -css=Active.css</code></pre>
All is Done.

<h2>参考</h2>
<pre><code>
=over 4

=item *

perldoc L&lt;perlpod>

=item *

perldoc L&lt;perlpodspec>

=item *

&lt;Programming Perl> Chapter 26 大骆驼书第26章

=back

</code></pre>
:) have fun.<br />
<ul>
<li>perldoc <a href='http://search.cpan.org/perldoc?perlpod'>perlpod</a></li>
<li>perldoc <a href='http://search.cpan.org/perldoc?perlpodspec'>perlpodspec</a></li>
<li><Programming Perl> Chapter 26 大骆驼书第26章</li>
</ul></div>
<p><&lt;Previous: <a href="RSS.html">给网页增加RSS</a>&nbsp;&nbsp;>>Next: <a href="050115.html">gb2312.enc</a></p>
<p><strong>Options:</strong> <a href='http://del.icio.us/post?title=%E6%80%8E%E4%B9%88%E5%86%99POD&url=http://www.fayland.org/journal/POD.html'>+Del.icio.us</a></p>
<strong>Related items</strong>
<ul><li><a href='050329.html'>Day [05.3.29] POD && Pugs</a> < <span class='digit'>2005-03-29 16:04:20</span> ></li><li><a href='pod2cn.html'>Perl 核心模块中文化</a> < <span class='digit'>2005-11-20 21:43:52</span> ></li></ul>
Created on <span class="digit">2005-01-14 00:40:37</span>, Last modified on <span class="digit">2005-05-21 00:16:39</span><br />
Copyright 2004-2005 All Rights Reserved. Powered by <a href="Eplanet.html">Eplanet</a> && <a href='http://catalyst.perl.org'>Catalyst</a> 5.62.
</body>
</html>